MacWorld 1996 July/Macworld (1996-07).dmg/Shareware Picks/Sparkle245/(Docs)/README 2nd

Text File | 1995-07-25 | 44KB | 833 lines

Sparkle: A new mac MPEG player.
-------------------------------
Documents for version 2.4.1
This document looks best in 9 point monaco.
On an MPW marks aware editor (like Alpha) this document has marks for
each section.

This document contains the following sections:
INTRODUCTION
LEGALITIES
SAVING TO MPEG
FAQs
WHY DOESN'T SPARKLE DO....
SMALL THINGS YOU MIGHT NOT HAVE NOTICED
THE FUTURE
HOW CAN YOU HELP IMPROVE SPARKLE?

------------------------------------------------------------------------------
INTRODUCTION

Hi there, friendly users. This is release 2.4.1 of my mac MPEG player.

Version 1.0 of this code was based on the Berkeley MPEG unix code.
(Anyone who wants to play with the Berkeley code can get it from
toe.cs.berkeley.edu in pub/multimedia/mpeg.) It was released as soon as
it was usable. This version no longer makes use of Berkeley code and uses
my own algorithms for greater speed, smaller memory footprint, and more
flexibility.

Version 2.0 of this code made use of the Berkeley MPEG encoder, available
from the same place as above. This encoding code has now been almost
completely rewritten by me, and uses substantially less memory than
before. For this release I merely concentrated on rewriting my own encoder.
As a result, the encoder behaves just like the old encoder except for
being a little faster and a whole lot less memory intensive.
In the near future I will add rate-controller to the encoder but that's
not yet ready for this release.

Notice that there is a section of this document called FAQs.
Please read it before sending me mail, thus avoiding wasting your time and
mine.

Please read all of this document before playing with the program. While
actually using the program is pretty simple, there are a few things you
should be aware of. Many of you may not care when I waffle on about
technical details. However I would ask all programmer readers (especially
people knowledgable about QuickTime, and especially Apple [and
ex-Apple :-( employees] to look at the tech sections and help me out with
comments and suggestions. Each time someone gives me a pointer on how to
do something it cuts a week or more off the release date of the next
version of Sparkle.

Features:
•    Standard mac interface with menus and windows.
•    Uses the QuickTime movie controller to control the MPEG viewing.
•    MultiFinder friendly, with good backgrounding behavior.
•    Saves MPEGs to QuickTime movies.
•    Can open multiple files at once.
•   Can open QuickTime movies and sets of PICTs.
•   Can encode MPEGs.
•     PowerMac native.
•    Free.

To run it needs at least:
I do not support Sparkle on less than System 7.5. If you refuse to
upgrade to 7.5, it is your responsibility to try to track down every
extension Sparkle needs. I no longer keep track of this info and cannot
help you in your search.
If you refuse to upgrade to 7.5, here's what you will need.
•    System 7.
•    QuickTime 2.0 (QT 2.0 with the QT PowerPlug on PowerMacs)
•   Sound Manager 3.0.
•    The Thread Manager (2.0 or higher on PowerMacs).
•   ObjectSupportLib and AppleScriptLib on PowerMacs.
•   Works much better with SCSI Manager 4.3
•    A 68020 or better.
•    1200K to play one 160x120 MPEG. Almost all memory allocation is done
    through temporary memory, so if you get a low memory message, close other
    applications. Increasing the partition size of Sparkle will not help
    much and will take memory from other applications.

I don't think there's much to say on the use of this program---you pretty
much run it like any other mac program. There is a section in this
document on tips that may not be obvious.
When opening files, you can choose to show all files, or only files with a
.mpg suffix.
If you choose the "show all files" option and open some random file, don't
be surprised when you are told that that is not a valid MPEG file.
If you set the option to change file types, the file type of the MPEG file
you are changing will be changed to a Sparkle file, which will give it a
nice icon and allow you to open the file by double-clicking on it.

Underneath the movie controller for each window is a progress bar which
will update itself when slow things are happening. If you have a fast
machine (say a Quadra or Centris) this won't have to update itself much,
except if you open large (and not too common) MPEGs---say 320x240. If you
really want to see what the progress update looks like, try having lots of
MPEGs playing at once, then switch Sparkle into the background.
If you save an MPEG to QuickTime using Cinepak, your machine may appear to
freeze while each frame is being converted. I have installed code to
reduce the extent of the freeze, but basically this is a bug with
QuickTime---the system just grabs control and won't let go for about five
seconds. Maybe this'll be fixed in QuickTime 2.0 if we're lucky.

I have tested this program extensively under low-memory conditions when it
opens files and plays them.  It should never crash under those conditions.
In 600K you can easily open, play and save to QT a 120x160 I-frame MPEG.  In
1500K you can open, play and save to QT a 320x240 IBP-frame MPEG.

Disk errors in various forms (bad sectors reading an MPEG file, no disk
space writing an QuickTime file, etc) will not crash, but the system will
put up an error alert and not handle the error very well (for example you
won't be given a chance to destroy old files to free up space on a disk).
Decent recovery from disk errors is on the list of things to do.

------------------------------------------------------------------------------
LEGALITIES

This program can be freely distributed.
If you want to include it on a CD-ROM collection, please ask me first,
but I'll probably allow you.
NOTE: Some authors will not allow their stuff to be distributed on CD-ROMs
for which people have to pay. I would ask these authors to consider things
more carefully. Many people (like myself) do not have very good ftp access
and a CD ROM of stuff is a godsend, even if we do have to pay a little for
it. Think about it.

If you feel a desperate need to thank me for this program, send me a
floppy of interesting MPEGs or QT movies you've picked up.
(Please don't e-mail me large files without warning.)
My paper-mail address is
    Maynard Handley
    20975 Valley Green Drive, Apt 226
    Cupertino, CA 95014
    USA

------------------------------------------------------------------------------
SAVING TO MPEG

The dialog box offering options when you save to MPEG is not that great
right now if you don't know what you're doing. I'm sorry---I'll fix it
when I have time, like everything else.

For a better explanation of how MPEG works, read the Technical Notes file
in this package, but here are rough details.

When encoding your MPEG you will need to decide what types of frames you
want to use. If you want your MPEG to be read widely, ie on PC systems,
you should consider using only I-frames. The most common MPEG decoder on
PCs is the Xing decoder which only understands the simple I-frame MPEG
format. If you want to get the best possible compression you should use
I, P and B frames, but then your MPEG will only be able to be read by
smarter decoders. A compromise is to use only I and P frames. This will
give you a lot of the compression benefit of I, P and B frames, but will
be faster to encode.

If you don't want to know the details of these frames, choose a frame
pattern from the popup menu.
If you want to create your own frame pattern, here are some details:
(If you don't want to create your own frame pattern, ignore these.)
1) The first frame in the MPEG will always be I. That implicit I frame is
    displayed in front of the frame pattern text you enter because it is
    always there and you don't need to put it in. That implicit I frame is
    only used for the first frame, after that your pattern is repeated as
    necessary. Thus if your pattern is BBPBBI, the encoder will encode frames
    using the sequence I BBPBBI BBPBBI BBPBBI ...
    (For people who care about MPEG details, this is the playback order
    of the frames. The actual order of the frames stored in the file
    will be be I PBBIBB PBBIBB PBBIBB.)
2) If you are using B frames, you have to start off with two referential
    frames, the initial I frame then either an I or a P frame.
3) The last few frames of the MPEG, if they would be B frames, will be
    converted to I-frames. (If this didn't occur, like in the original
    Berkeley encoder code before I munged it, you will lose those final
    frames.)
4) Don't create too long a pattern of Ps or Bs. You'll start to lose
    quality and random access into the movie will become more granular. The
    presets I've given should guide you as to sensible selections.

Once you have chosen a frame pattern, you'll need to select the amount of
compression you want to use. This is set by the I, P and B quantization
levels. The values the dialogs gives as defaults will usually make sense
but if you want to change them:
1) The values are restricted to the range 1 through 31 inclusive.
    A quantization of 1 is the highest quality, a quantization of 31 is the
    lowest quality.
2) Normal quality is a quantization of about 8. Low quality is a
    quantization of about 16. High quality is about 6.

You can choose from various algorithms for generating P and B frames. I
haven't explored these in detail and they may change when I have time to
look at them. For now the important things to note are
1) They all seem to generate about the same quality, and about the same
    file size.
2) They are ordered in the menus by speed, with the fastest ones first.
3) The B-frame exhaustive search will take approx forever to do anything.
    Try it once to see what I mean, but don't expect to use it for anything
    useful.
As I explore these more and start diddling the code, I'll provide more
explanation.

If you save to MPEG, because of the non-causal algorithms used by MPEG
compression, frames are not compressed in the order they are displayed.
This means that if you are using B-frames and stop the compression before
it reaches the end of the source movie, the encoder may have queued up
some frames it needs to compress to make the MPEG file consistent.
If this is the case, Sparkle will have to encode those queued frame before
it stops the compression, so it won't stop immediately.
The message window will tell you how many frames have been queued so you can see
how things are going. If you have the speech manager installed, Sparkle
will also tell you how many frames are left, which you may find more
convenient.

You can set the frame rate from a popup menu. When the dialog box opens,
the frame rate of the MPEG or QT movie you are converting has its frame
rate read in and used to set the initial frame rate. So usually you won't
want to change the frame rate. Note that there are a limited set of frame
rates because MPEG only supports a very few frame rates. So the best one
possible is chosen.
Note also that frames are laid down with that frame rate which may cause
the movie to speed up or slow down. No frame interpolation is done to
ensure that perception remains correct across frame rate variation.
This'll be changed at some point, but is not a high priority compared to
sound.

When an MPEG is encoded the frame currently being encoded may be compared
to the original version of a previous frame, or to what you get when you
decompress the MPEG compressed version of the earlier frame. The latter
alternative is called ``Decoding Reference Frames''. If you use this
latter alternative the compression takes a little longer but results in
files a few percent smaller and slightly better quality. I'd recommend
you leave this option selected.

An MPEG can be encoded using using what are called half-pixels which means
that some pixels in a P- or B-frame are specified as an average of pixels
around them.  If you use half-pixels the MPEG created will be a few percent
smaller than if you don't use half-pixels and the quality will appear
better IF you play the MPEG on an MPEG player that handles half-pixels.
However if you use an MPEG player that does not understand half-pixels the
result may look pretty shabby in places where there is a lot of action.
Also, using half-pixels makes encoding slower and increases the amount of
memory used by almost two-thirds. For these reasons I'd recommend not
selecting this option.

------------------------------------------------------------------------------
MENU OPTIONS

Here are various points related to the menu options:

• File| Save As:
    This allows you to start saving a movie or pseduo-movie
    (made from a set of PICTs) as an MPEG or QuickTime file. Once you start
    the save it continues in the background. This menu item changes to
    File| Stop Saving which will stop the saving at once.
    You may want to pause the saving but not stop it, for example so that
    you can play another movie at top speed. To pause, simply click anywhere
    in the movie controller or type any key.
    When the saving is busy working away the movie controller play button
    shows a pause symbol, because if you click there it will pause the saving.
    When the saving is paused, the movie controller play button shows a play
    symbol because if you click the saving will resume.
• Image|Grow or Shrink
    The scaling of the window at any time is given in the title bar.
    When the title starts with *1, the movie is its natural size.
    With *2 the movie has been doubled in size.
    With /2 the movie has been halved in size.
    For now if you expand or shrink movies beyond their natural size
    playback will be much slower and quality may not be as good. I'll be
    adding code to fix this soonish.

• Image| Hide All
    You can hide or show all the decorations below the movie windows. The
    easiest way to do this is with the tab, shift-tab and control-tab keys,
    or with command-H. You may want to do this because the decorations
    irritate you or because hiding the decorations makes playback speed a
    few percent faster.

• Playback| Play All Frames:
    If this is set, every frame of the movie will be played. The movie will
    try to play in real time, but may be slower than real time if necessary.
    It will never be faster than real time.
    With quicktime movies sound is disabled when this option is on.
    When this option is off, the movie will play back in real time which may
    mean skipping some frames. For MPEGs, how well this works depends on how
    fast your mac is. (Also read the section on play rate below.)

• Playback| Play at Double Speed or Play at Half Speed:
    These options set the  movie to play twice as fast, at the normal rate,
    or twice as slowly. Note that if Play All Frames is active, playing the
    movie at double speed may be no faster than playing it at normal speed
    because both ways the calculation of each frame is overloading the mac.
    Some MPEGs look jerky and too fast when played at their normal speed and
    with Play All Frames switched off. This is because the MPEGs have been
    encoded at too high a frame rate. For example the original movie may
    been sampled at 12 frames per second but it's encoded as an MPEG of 24
    (or 23.976) frames per second. This happens because the lowest possible
    frame rate with MPEG is 23.976 fps. So if this happens, you may want to
    set the MPEG to play at half speed.
    You can also control the speed at which movies play by command-clicking
    in the steppers of the movie controller.

• Playback| Set Frame Rate is a generalized version of the above. If you
    click the Save in File check box, the new frame rate you have chosen
    will be saved in the MPEG file and used as the default in future. You
    probably don't want to do that until you've tried the rate and seen that
    it works properly. If the rate of an MPEG file seems to fast, is has
    probably been coded with an inappropriate frame rate. In this case it is
    most likely the frame rate is 7.5fps, so try that first, and next try 15fps.
    Chances are one of those two is the correct rate.

• Edit| Preferences| Faster Mode:
    If you set this option, whenever Sparkle is busy, either playing movies
    or encoding movies, it will not yield time to background applications.
    This makes playback a little faster and smoother.
    However if you have an application doing something in the background,
    for example a modem download or a background compile, you might want to
    deselect this option.
    By my testing, when Faster mode is on Sparkle uses up about 90% of the
    CPU. When faster mode is off Sparkle uses up about 70% of the CPU.
    (When Sparkle is in Faster mode it still has to use the EventAvail() trap
    every so often to see if the user has issued a command, moved the window,
    grown it or whatever. It's these calls to EventAvail() which can yield the
    CPU to other processes that suck up the 10% of the CPU not used by
    Sparkle in Faster mode. Anyone know how to perform the equivalent of
    EventAvail() without allowing the Process Manager to yield?)

• Edit| Strip Resources:
    Sparkle 2.4.1 now stores two types of info in the resource fork of an
    MPEG file (the MPEG data is all stored in the data fork). The frame rate
    that you have chosen for the MPEG through the Playback| Set Frame rate
    dialog is stored. Also stored is all the index info into the MPEG that
    Sparkle builds the first time it opens the MPEG. This makes opening the
    MPEG on susbequent occasions faster.
    However there may be reasons why you don't want this information in the
    resource fork. For example if you are building a Web page and your web
    software is so dumb it can't handle files with a resource fork, you'll
    want to strip the resource fork. (If the software is smart enough to
    send only the data fork of a file and not the resource fork, that is
    perfect and you won't need to do anything.)
------------------------------------------------------------------------------
MPEG PLAYBACK PREFERENCES

The MPEG Playback Preferences dialog (use command-R or look under the
Preferences menu under the Edit menu) allows you to set general playback
preferences. Most of these are concerned with how you wish to balance
playback speed against playback quality. Note that whatever settings you
choose for playback, when you save an MPEG file to another format all
settings are switched to the highest quality while the save is in
progress, so you don't need to worry about losing quality that way.

The other quality options are used depending on the screen depth of the
screen on which the MPEG is playing. So if your MPEG is on a 16-bit
screen, the 16-bit color options are used.
• Use 4x4 IDCT:
    One time-consuming part of MPEG decoding is the IDCT which is somewhat
    like a Fourier transform. This should be performed using a matrix of 8x8
    coefficients. If you select this option only a 4x4 subset of that matrix
    will be used. This makes the calculation a lot faster, but the cost is
    some blurriness to the image which is usually acceptable.
•Use half-pixels:
    Half-pixels are a scheme whereby certain pixels in the image are
    represented in the MPEG file as an average of nearby pixels. Calculating
    these averages takes time but improves quality. I'd recommend not
    bothering with half-pixels on an 8-bit color screen because the dithering
    hides the fine detail they reveal. For other screen depths you decide.
    Some MPEGs will not be affected by this setting, because they were coded
    not to use half-pixels.

• 24-bit screens display options:
    The high quality setting corresponds to clipping RGB while the faster
    setting does not clip RGB.
    This is the same sort of issue as the Clip YCrCb note above, only
    occurring at a later stage in processing. Some MPEGs look fine with
    neither form of clipping, some only need one or the other, and some need
    both. (This option is not an issue for 8 and 16 bit screens because they
    use a different way of calculating RGB for their display---not as high
    quality as the 24-bit method, but good enough for the given screen
    depth.)
• 8-bit color screens display options:
    You have a choice of three dither options on an 8-bit screen.
    * Fast dithering uses an algorithm I invented. It is phenomenally fast,
    but not the greatest quality. It looks especially bad for things that
    need very sharp edges, like text. (It also uses 128K of storage to do its
    thing, so if you're low on space you may want a different option.
    When this option is activated for the first time --- for example when
    you switch to 8-bit colors screen depth from some other depth, or when
    you first open an MPEG under 8-bit screen depth --- these 128K of tables
    have to be calculated which takes about 1.5 sec on my Quadra 610.
    In a future version of the code I'll implement ideas I have for removing
    this delay.)
    * Use 16-bit pixmap calculates everything using a temporary 16bit pixmap
    which is then dithered on the screen using QuickDraw. It's a compromise---
    the quality is better than fast dithering and it uses less memory than
    the 24-bit scheme.
    * Use 24-bit pixmap works like 16-bit pixmaps, but all calculations are
    performed on a 24-bit pixmap (using RGB clipping).
    This gives the best results, but is slower than the 16-bit pixmap case and
    uses more memory.
    * I hope to improve the quality of the fast dithering algorithm in the
    near future.
    * Also at some point I'll add code to allow you to set an optimal palette
    when playing on 8-bit color screens. At present I simply use whatever
    palette the screen is using, usually the system palette.
• 16-bit screen display options:
    You have three options.
    * The fast option uses a lookup table directly on the MPEG YCrCb data to
    get RGB values. This is faster but gives lower quality.
    * The 16bit high-quality option calculates the RGB values properly (with
    greater precision than using a lookup table). It gives better quality
    but is slower. (At present I haven't yet written the code for this
    option so it is disabled.)
    * The 24bit pixmap option calculates results using a 24-bit pixmap (and
    RGB clipping), then dithers the result to the 16bit screen. It gives the
    best quality but is slowest.

• For 8-bit grey screens:
    Two points to note.
    * Is your graphics card set to grey mode? If you have a grey screen but in the
    monitors control panel you have set your graphics card to color, Sparkle
    will think it's on an 8-bit color screen. This will give you slower
    playback and lower-quality results.
    * For the fastest possible playback, I assume that the screen palette is
    set to the system palette. On an 8-bit grey screen there is never any
    reason to change this. Nonetheless, some applications feel they simply
    have to perform this pointless exercise whose only effect is to reduce
    the quality of what's displayed by other applications. (Would you be at
    all surprised to learn that Word, one of the masterpieces from those
    geniuses at Redmond, is such an application? I though not.)
    What this means is that if you are running Word (or another of these
    ill-behaved applications) in the background, Sparkle will playback MPEG
    files somewhat slower than it should.

In summary:
The fastest playback possible is on a 8-bit grey screen, followed by
  8-bit color, then 16-bit color, then 24-bit color.
For fastest playback, deselect the ClipYCrCb option,
  select the Use 4x4 IDCT option,
  deselect the Use Half-Pixels option
  for 8-bit screens use fast dithering
  for 16bit screens use 16bit fast
  for 24bit screens use 24bit fast
  use command-H to hide all the decorations below the video window.
For highest quality playback, use the deepest screen-depth you can,
  select ClipYCrCb
  deselect the Use 4x4IDCT option,
  select the Use Half-Pixels option
  select the 24-bit pixmap option

Decoding MPEGs requires lots of computation, but can be made faster by
sacrificing some quality. I've tried to allow you to make your own choice
about which you prefer. But remember I can't work miracles. For example I
can't magically give you an 8-bit color dither algorithm that gives the
same quality as the QuickDraw but runs at the speed of my fast dithering.
I'll try to improve the quality of the high-speed options in future, but
I can't promise anything.

The one other item in this dialog box is the
"Prefer 8-bit color to 8 bit-grey" checkbox. This is only relevant to
people who have more than one screen, at least one of which is grey and
at least one of which is color.
When Sparkle opens a file it orders all the screns available by screen
depth and tries to open a window on the deepest depth screen. But if you
have one screen set to 8-bit grey and the other set to 8-bit color it
can't know which you'd prefer, hence this setting. You may prefer the
color screen because any color is better than none, or the grey screen
because it gives faster playback and no fuzziness from dithering.
(After ordering the screens by depth, Sparkle notes where other movie
windows have been placed and tries to place the new window so it doesn't
overlap any of the old windows. Also, if the window opened is large than
any screen, it will be opened at half size or whatever so it does fit on
the screen. I hope you like this algorithm. It works better than what
every other program I've seen uses. If you have comments about it, please
mail me.)

------------------------------------------------------------------------------
PICT FILES AND PSEUDO-MOVIES

Sparkle can open a set of PICT files to convert them to an MPEG or QT
movie. This may be useful if you have enough program, like a graphing
program, that creates a set of PICTs, or if you have a set of medical
scans or such.

The only picture format Sparkle understands is PICT, the Mac standard
picture format. I do not plan to change this because there are lots of
programs out there, many of them free and many of them capable of running
in batch, that will convert whatever format you have to PICT.

Once you have your pictures in PICT format, they need to be in the same
folder and given the same name so that Sparkle can link them together.  For
example, if these pictures represent x-rays of your head, call them
myHead.1, myHead.2, etc.  They must be named name.# where name is common to
all files and # is a number.  The numbers don't have to start at zero or
one, and don't have to be contiguous.  However they must all be positive
integers.

From the open files dialog open one of your PICTs---whichever one you get
to first, it doesn't have to be the lowest numbered one. Sparkle will
scan the folder for other PICT files with that name and a number added,
order the files it finds, and display them all in a movie window.
You can now treat this pseudo-movie like any other movie. You can grow or
shrink the window, step forwards or backwards, etc. You can play the
movie if you like, but for these PICT pseudo-movies I set the framerate
to only one frame per second. Decoding a PICT can be fairly slow---it
involves disk access and lots of memory---so don't expect this to work
wonderfully. You can now save the pseudo-movie as an MPEG or QT movie
just as you would normally.

The PICTs may be different sizes, but the window opened will be the size of
the PICT you select in the open file dialog box. The other PICTs will be
scaled to fit this size window and may not look too good. I wouldn't
recommend using a set of PICTs that aren't all the same size.

Note that for now I don't do anything special when I draw the pictures.
In particular this means on screens that aren't 24-bit or 16-bit I don't
dither the picture. This will be fixed fairly soon. For now everything
all works and it doesn't affect the quality of movies you create.
I'll also be adding code to save MPEGs or QuickTime movies as a set of
PICTs fairly soon.

------------------------------------------------------------------------------

QUICKEYS AND BATCH CONVERSION

I won't have AppleScriptability in place for a few months, but I have
been asked by some users for a rudimentary support for batch conversions.
Specifically people wanted a way for Sparkle to indicate that it was done
encoding a given file.

I have provided such a capability for QuicKeys users in a very crude
fashion. When Sparkle has finished converting a file to a different
format it will toggle the cursor from the standard arrow cursor to a
thick cross for one second.
Note which cross this is: It is not a thin one pixel wide cross, neither is
it a spreadSheet like cross with arms a few pixels wide. This cross has
arms that are two pixels wide.

To use this capability in QuicKeys, you want to put in your sequence a
Wait..  command. Make the Wait command a WaitForCursor variant, and set
the options to wait until the cursor becomes ``Other...''. In the
``Other'' dialog box choose the appropriate cursor---in my version of
QuicKeys it's the fourth cursor along. UnSet the Test for Mask box and
set the Test for Cursor box.

I would recommend that you structure your sequence like this:
    Wait ...      ---Wait for the cursor
    Pause...    ---Pause for a second
    Pause...    ---Pause for five seconds or so
    Do your thing.

The first pause in the above is to wait until Sparkle finishes its one
second flash of this cross cursor. The second is to wait for general disk
activity and such to finish. At that point you can then go on to whatever
the rest of your sequence does, like maybe close Sparkle then open it
again with a new file.

------------------------------------------------------------------------------

FAQs (Frequently asked questions).

• I try to play MPEGs but my Mac starts speaking numbers or asks me over and
over to select a voice.
    You have the Speech Manager installed on your Mac including a little
    extension called ``Speech Media Handler''. Speech Media Handler speaks
    the text of movies that include a text track, and Sparkle plays MPEGs
    by creating a dummy text track as part of the process of faking QuickTime
    into accepting MPEGs. I'd recommend ditching Speech Media Handler. I've
    never seen a place where it is useful and right now it's kinda a cute toy
    idea that escaped from Apple. Maybe in a few months they'll give it a
    programmer interface and make it more useful.

• I've downloaded (or uploaded) an MPEG using Mosaic/WWW and when I try to
play it Sparkle says it's not an MPEG file. But if I ftp the file with
Fetch or suchlike it works fine. What's happening?
    Be very careful when transferring files over the Internet with MacBinary.
    Fetch and many such programs automatically strip MacBinary from files,
    but Mosaic does not appear to (maybe this will be fixed soon). So
    if an MPEG is stored at a Mosaic site using MacBinary, all Mosaic users
    trying to download it will have problems.

• Why does my MPEG have the occasional block of garbage, mostly colored
green?
    Some part of the MPEG file has become corrupt. This usually happens with
    MPEG files that have been uuencoded and have had a character or two lost
    or changed.
• Why are large parts of my MPEG filled with green garbage, or with parts
of earlier scenes.
    You have probably downloaded the MPEG file using gopher or ftp in ASCII
    format. The file is now useless. Download it again using BINARY mode.
    Better still, set your gopher or ftp application always to download .MPG
    suffix files in BINARY---don't trust its AUTOMATIC mode.
• Why is the first frame of my MPEG all green?
    Some people out there when they create an MPEG file, randomly start it
    where they feel like it.
    The consequence is that the first some bytes of the file are garbage and
    appear as an all green first frame.
    If you have one of these MPEGs, whenever you jump to the first frame, you
    won't see the first frame, but simply the last frame you were looking at. This
    is a consequence of the way Sparkle handles errors in the MPEG file format.
    Mostly it works well, but in this particular case it isn't great.
    It is not too easy to work around this because of the many different ways
    in which the MPEG can have garbage at the start before valid data begins.

• Why at the end of an MPEG is the last frame the same as the second to
last frame?
    Some MPEGs just are created this way, with the last two frames as
    duplicates. This is a problem with those files, not a bug in Sparkle, and
    one just has to accept it.
    A similar type problem is that some video that's been converted to 30fps
    from 24fps film has duplicate frames every so often, and agin one just
    has to accept this for now.

• What does the Thread Manager do? Why do you make such a fuss over it?
    The Thread Manager provides a way for a programmer to create a number of
    tasks within an application and have those tasks all run together. So
    with Sparkle every time the user asks for something that will takes some
    time, like playing an MPEG or saving a file in some different format, I
    create a task that does that work. If the Thread Manager isn't present,
    you, the user, can't create a number of these tasks and switch between
    them---you are restricted to doing only one thing at a time.

• When I started saving a file to MPEG, it got through two frames then sat there
doing nothing for a long long time. Did it crash?
    Especially when saving to MPEG, Sparkle creates a large number of blocks
    of memory. If the mac runs out of memory partway through performing
    this saving, it will run around trying everything it can to scrounge memory.
    On my Quadra 610 I have seen it sit there for 45 seconds trying to free up
    memory before it concludes that there's nothing it can do and pops up an
    error message. I guess on slower machines it might sit there for up to two
    minutes. Just be patient and wait a while before concluding things
    have crashed.

• Where can I get MPEG files?
    An ftp sites is 2k-ftp.CS.Berkeley.EDU in pub/multimedia.
    (This site used to be called toe.cs.berkeley.edu.)

    Here are some WWW sites
    http://www.ccsf.caltech.edu/~johns/sl9.html  (CalTech)
    http://newproducts.jpl.nasa.gov/sl9/images.html  (JPL)
    http://seds.lpl.arizona.edu/sl9/sl9.html  (U. Arizona)

    This phillips site sometimes has MPEGs.
    ftp.cdrom.com: /pub/cdrom/incoming

• Where can I find more about MPEG?
    Read the UseNet MPEG FAQ. This is published in news.answers every so
    often, and can beobtained through
    http://www.cs.tu-berlin.de/user/phade/

• How can I deal with AVI files?
    At mac.archive.umich.edu (and probably at sumex)
    in /mac/graphics/graphicsutil is vfw1.1utilities.sit.hqx
    which handles AVI files and is supposed to work pretty well.
    I've also been told about
    ftp://ftp.ctr.columbia.edu:/pub/DA/incoming/vfw11mac.hqx
    which looks the same to me, judging from the name, but which I'm told is
    better than the above.

• What can I do about MPEG sound files?
    Use this program for now, till I include this functionality in Sparkle.
    ftp://mrcnext.cso.uiuc.edu//pub/info-mac/snd/util/mpeg-audio-032.hqx
    Also look at the Internet Underground Music Archive (IUMA) ftp site,
    sunsite.unc.edu (152.2.22.81) /pub/electronic-publications/IUMA
    for various MPEG audio files and code/apps for a variety of machines.

------------------------------------------------------------------------------
WHY DOESN'T SPARKLE DO...

•    Why doesn't Sparkle read .gl, .dl and .fli files?
One reason is that those file formats are awful. They give these dinky
low contrast horribly dithered images no-one would want to look at, and
they usually only have about 10 frames. Maybe, years from now, I'll add
those conversions, but they're about as low a priority as you get.
At mac.archive.umich.edu (and probably at sumex)
in /mac/graphics/graphicsutil is macanimviewer1.05.sit.hqx
which handles these various cheapo formats so you might want to grab it.

•    What about audio?
MPEG has audio compression as well as video compression. I've been doing
lots of reading into this and pretty soon will start coding for it.

•    What about Video for Windows?
I would be nice to support .AVI files. But right now I know nothing about
.AVI beyond the fact that it exists. Again any info anyone has is
appreciated. Until I know how .AVI works, how it fits into the windows
environment etc, I can't even tell you if it's practical for Sparkle to
try to support .AVI, let alone start the necessary coding.

•    Why don't you write an MPEG codec?
MPEG support under QT is through the emchanism of a new Media Handler, not
simply a codec. This si being worked on but it's a  non-trivial problem.

------------------------------------------------------------------------------
SMALL THINGS YOU MIGHT NOT HAVE NOTICED

The movie controller behaves pretty much like a standard QT controller.
You can step forward and backwards, hold down those buttons to play
forwards or backwards and click or drag in the central region to go to a
random point.
You can use the forward and backward arrow keys to step.
You can option click in the forward and backward steppers to go to the
beginning or end of the MPEG. Likewise using option forward or backward
arrow.
You can start the movie playing using either return, spacebar, or
command forward arrow. You can stop playing using spacebar or return.
You can yet play backwards by using command backward arrow.

The visual clue that the movie is being saved is that
the movie controller loses its controls and shows only a relative position.
This is not a particularly obvious fact and may at some point be changed.
For now it works once you realize this fact.

When a movie is being saved, you can either stop the conversion
or pause it. To stop the conversion, use command-S (or the equivalent
menu option.) This will save the movie using the frames created so far.
To pause the conversion use command-P, or the equivalent menu option, or
click in the movie controller.
The  saving will stop until you start that movie playing again. This is
occasionally useful if you want to pause a cinepak conversion to do a
short job on your mac.
You can tell whether a movie is actively being saved or paused being
saved by looking at the indicator in the title bar.
If the first character in the title bar is
  S the movie is actively being saved,
  P the movie is paused being saved,
  R the movie is in realtime playback mode
  A the movie is in play-all-frames playback mode.

If you are partway through a movie and save, the movie will be
rewound to the beginning for you. You do not need to be at the start of a
movie to save.

You can save only part of a movie by selecting that portion (using the
shift key and the arrow keys or the mouse), then hitting command-S.

You can set the temporal quality options when saving to QuickTime
separately from the spatial quality options. If you need to do this, hold
down the option key while using the quality slider, and it will become a
temporal quality slider.

To improve the smoothness of MPEG and QT playback, while movies are playing
Sparkle only examines the event stream in an approximate fashion. The result
of this is that incoming Apple Events and update events are not processed but
stay in the queue---only mouse downs and keyboard clicks are noticed
immediately. This is not a big deal because most of the time you're not
changing things while your movie plays. But if, eg, you change the screen-depth,
say using some popup menu INIT while a movie is playing, the easiest way to
make Sparkle aware of the change is simply to click the mouse a few times.
If you don't understand the issue here, ignore it---you won't need it.

------------------------------------------------------------------------------
THE FUTURE

The basic outline for now is
    2.5 Cleaned up faster, smaller version of 2.0.
    3.0 Handles sound.
    3.5 Cleaned up faster, smaller version of 3.0.
While adding these large additions I'll fix small things as I go, and as
I have time. I don't see the user interface improving much for some
time---more important things need my time.

I also want to add stuff to allow us to create movies. Morphs, special
effects, that sort of thing.

------------------------------------------------------------------------------
HOW CAN YOU HELP IMPROVE SPARKLE?

•    Any info on psycho-acoustic encoding?
•    Any info on Microsoft Video for Windows?
•    Any bug reports.
•    Any ideas you have or suggestions. Your suggestions may go onto the
    list of things to do (currently two pages of single line items) but will
    probably be acted upon at some point. People have suggested several
    things to me I would not have thought of myself, so I do want your
    feedback.
------------------------------------------------------------------------------
THANKS

* Many people all over the internet have helped me write this code.
* Thanks to the people at Berkeley. Even though I've completely replaced
    their MPEG playback code with my own, they helped get this project started.
    And, until I rewrite it, I'm using their MPEG encoding code.
* Thanks to various usenet personalities who answered mac programming
    questions, mailed me quicktime header files and such. Special thanks to
    ldo in New Zealand, and Jon W{tte in Sweden, and bryanw, keeper of the
    MPEG FAQ, who mailed me about the Stanford MPEG encoder.
* A special individual thank you goes to DS (he didn't want me to give his
    name but he knows who he is.) DS mailed me a CD ROM and ten floppies of
    information about QuickTime components after I complained that Apple was
    not making this information easily available. He's also provided me with
    information on QT 2.0 which will gradually be assimilated into Sparkle.
* Thanks to Gene Chalfant who passed on a paper from NASA containing some
    interesting ideas on IDCT alternatives.
* Thanks to the mystery person in Britain who sent me some QT 2.0
    information in an envelope with no name attached to it.\
* Thanks to Jamie McCarthy for code for touching Finder folders.
* Thanks to Troy Gaul for the Infinity Windoid.
* Thanks to Richard Lim for the current set of icons used by Sparkle.
    (Which I modified a little so it's probably best to blame me rather than
    him for poor design choices if you don't like them.)
* Thanks to Stuart Cheshire for mailing me a QT 2.0beta CD-ROM and misc
    useful info.
* Thanks to everyone who's mailed in bug reports or suggestions. Even when
    I can't implement suggestions at once, they go on the list for inclusion
    in a few months.
* Thanks to Apple for making the greatest computers in the world.
    (Though sadly they seem to be going completely clueless with regard to
    how to distribute their various new ideas. I fear if they don't get their
    act together about this soon, NO-ONE will support these new things
    because developers will have no idea whose machine has what on it.)
* Thanks also to Symantec for creating such a great programming environment.
    This program was written with Think C 5, then Think C 6  and now Think C 7
    using the Think Class Library. Having coded on Windows, X-windows, and
    the Mac, I can unreservedly say that the Mac is by far the most pleasant
    platform for a programmer.
* Thanks to Richard Cowgill for providing me with the cool looking
    picture to use for a startup screen.
* Thanks to Stuart Cheshire (again!) for nagging me about very MPEGs in
    very small windows and getting me to make the window-shrinking code behave
    a little nicer.
* Thanks to Chris Petersen for the nice new Sparkle folder icon.
* Thanks to Apple (again!) for sending me a PowerMac to use so I could
    code up a native version.
* Thanks to everyone who submitted bug reports and ideas.
* Thanks to Frank Hauptmann who sent me a Video-CD so I can test Sparkle
    and my MPEG code against it.

(If I've forgotten your name here by mistake and you really deserve to be
here, please remind me.)

Maynard Handley
[e-mail]
March 14 1995